home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Cream of the Crop 20
/
Cream of the Crop 20 (Terry Blount) (1996).iso
/
os2
/
pmp43.zip
/
DBUG.TXT
< prev
next >
Wrap
Text File
|
1996-07-06
|
16KB
|
468 lines
******************************************************************************
DBug Definition
******************************************************************************
DBug is a flexable and easy to use real-time Debugger for the software
engineer/developer that provides debugging capabilities that are impossible
for the source-level debugger, easier to use, and often more convenient.
The concept of DBug is simple. You place 1 or more "DBUG" statements in your
program source code at a strategic point for the purpose of displaying a
message, the content of variables or memory, or time stamping a point of entry.
Compile and run your program(s). While or after running your program(s), you
can view the current results via the "DBug" window or view the DBug log file
to browse your DBug results.
******************************************************************************
Using DBug
******************************************************************************
When you compile your programs you include the C/C++ header file "dbug.h" and
specify the compiler directive "-DDEBUG". You must link your program with the
DBug Import Library "DBUGAPI.LIB" to resolve externs.
Once you're done testing and want to remove the DBUG statements for
"production" use, you may:
1. Recompile your program(s) WITHOUT specifying the compiler directive
"-DDEBUG". The compiler will ignore the DBUG statements. Linking with
"DBUGAPI.LIB" is now unnecessary.
2. Manually remove each DBUG statement. Recompile and link.
It is recommended is that you leave the "dbug.h" include file in the
program(s) and choose option 1 above. This allows you to, with just a
recompile, have your run-time debugging enabled quickly for testing.
DBUG statements are C/C++ macros which map to a single API. There is a
"generic" DBUG macro for any use, and specific macros for each unique
standard C data type&colon.
o The DBUG macro is generic and allows you to display the contents from
any data type as well as any chunk of memory.
o The DBUGM macro displays a simple message of your choice.
o The DBUGS macro displays the contents of a SHORT data type.
o The DBUGL macro displays the contents of a LONG data type.
o The DBUGI macro displays the contents of a INTEGER data type.
o The DBUGD macro displays the contents of a DOUBLE data type.
o The DBUGC macro displays the contents of a CHAR data type.
o The DBUGZ macro displays the contents of a String data type.
o The DBUGP macro displays the contents of a POINTER data type.
o The DBUGOPEN macro opens a new DBug log file
o The DBUGCLOSE macro closes a the DBug log file
o The DBUGSTOP macro terminates the DBug facility
Each DBUG statement will cause an IPC message to be build and sent to the
central DBug program. The DBug program will then display the message in his
standard format and log it for later recall - if logging is turned on.
If the DBug proram is not presently running to receive these requests, your
DBUG statements will be ignored at run-time. The effort required to complete
a single DBUG within your program(s) is very minimal and insignificant.
The DBug program can be started and stopped at any time - even when programs
are actively DBUGing. If restarted, DBug will continue pulling DBUGs from his
queue and displaying/logging them.
DBug will handle bursts of DBUGs easily as he offers a 256K maximum buffer.
DBug will only allocate/commit enough memory to hold each DBUG request - not
the whole 256K. The 256K buffer is therefore used optimally and requires
little real memory from OS/2.
When monitoring DBug, minimize the window if large amounts of DBUGs are be
displayed. This will significantly improve how fast DBug displays and reduce
the overhead of displaying results.
DBug has two log files and are created in the drive/directory where DBug was
started. If started and control from PM Patrol, these log files will reside
in the directory from where PM Patrol was installed and started.
o The primary and active log "DBUG.LOG" contains current data.
o The backup log "DBUG.BAK" contains the previous primary data after a new
log file is opened.
When logging is opened, a DBUG message is placed at the beginning of the Dbug
log file.
Note: DBug log files are automatically recycled at midnight so that under
continuous operation, each log will contain a full 24 hours of information.
Therefore, up to 2 days (primary and backup) of DBug information can be
reviewed any time.
If Dbug has nothing to do, absolutely no CPU is used. The small amount of
DBug memory requirements are "swappable" to make room for more active
demanding programs.
DBug is a high performance debugging tool for even the most intense
environments. When the Dbug window is minimized or DBug is running in "Quiet"
mode, DBug can handle several hundred DBUGs per second. Even more for highend
Pentium or PowerPC processors.
******************************************************************************
DBug Programming Files
******************************************************************************
The DBug software contains 3 files for DBug programming purposes&colon.
o DBUG.H is a C/C++ header containing the macros for DBug. "Include"
this header file in your C/C++ programs.
o DBUGAPI.LIB is the Import Library to link with to resolve DBUG APIs. You
must link (LINK386) with this Import Library to resolve external
references and is specified in the LINK386 options.
o DBUGAPI.DLL is the Dynamic Link Library which holds the actual code of APIs
For compiling and linking, append the installation path used for PM Patrol to
the following statements in your CONFIG.SYS:
o "LIB" statement for the API import library (DBUGAPI.LIB).
o "INCLUDE" statement for the API C/C++ header (DBUG.H).
Make sure the DBug DLL is available at run time by appending the installtion
path used for PM Patrol to the following statements in your CONFIG.SYS
file:
o "LIBPATH" statement for the API DLL (DBUGAPI.DLL).
******************************************************************************
DBug Macro Set
******************************************************************************
DBUG() Macro
------------------------------------------------------------------------------
The DBUG macro is generic and allows you to display the contents from any
data type as well as any chunk of memory.
Prototype: ULONG DBUG (PVOID address, USHORT size, PCHAR note)
Parms: address ... Address to displayed/dumped
size ... Size of data type or memory to be display
note ... A personal description of your choice
Returns: NO_ERROR ... Successful with no errors, or error code
Example:
--------------
#include <stdio.h>
#include <stdlib.h>
#include <dbug.h>
...
CHAR array[60];
DBUG(array, sizeof(array), "my array");
DBUGM() Macro
------------------------------------------------------------------------------
The DBUGM macro displays a simple message of your choice.
Prototype: ULONG DBUGM(PCHAR message)
Parms: message ... A personal description of your choice
Returns: NO_ERROR ... Successful with no errors, or error code
Example:
----------
#include <stdio.h>
#include <stdlib.h>
#include <dbug.h>
...
DBUGM("Point 1 of program");
DBUGS() Macro
------------------------------------------------------------------------------
The DBUGS macro displays the contents of a SHORT data type.
Prototype: ULONG DBUGS(PSHORT address, PCHAR note)
Parms: address ... Address of short to be displayed
note ... A personal description of your choice
Returns: NO_ERROR ... Successful with no errors, or error code
Example:
----------
#include <stdio.h>
#include <stdlib.h>
#include <dbug.h>
...
USHORT variable;
DBUGS(&.variable, "my variable");